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0OS/3 TECHNICAL BULLETIN SUMMARY 


The following Technical Bulletins are published for the OS/3 system. 
Current items are identified with an "*" in colum one; scheduled 
items are identified with an "**" in the date colum: 


- SYSTEM REL.# DATE ORDER# ITEM and DESCRIPTION 
*OS/3 4.3 1/78 UP-8605.1 OS/3 Technical Bulletin #1 


(This document presents an 
overview of the UTS 400 
support and gives some 
user guidelines.) 


*OS/3 4.3,5.0 3/78 UP-8605.1-A OS/3 Technical Bulletin #1-A 
(This update contains page 
replacements to UP-8605.1.) 


*OS/3 ALL 4/78 UP-8605,.2 OS/3 Technical Bulletin #2 
(This document provides 
a list of the options that 
can affect the performance 
of an OS/3 IMS 90 system.) 


*OS/3 4.3 1/78 UP-8605,3 OS/3 Technical Bulletin #3 
(This document is a User 
Guide for the UTS 400 
CHARACTER PROTECTION MODE 
available with release 4.3.) 


*O0S/3 5.0 7/78 UP-8605, 3-R1l OS/3 Technical Bulletin #3-R1l 
(This document contains 
updated guidelines for 
the UTS 400 CHARACTER 
PROTECTION MODE available 
with release 5.0.) 

*OS/3 “2 11/78 UP-8605.4 OS/3 Technical Bulletin #4 

,6.0 (This document contains 

information on the use of 
the 8413 DISKETTE FILE 
CREATION UTILITY.) 


*OS/3 3.2 5/79 UP-8605.5 OS/3 Technical Bulletin #5 
(This document contains 
information on the use 
of DATA UTILITIES for 
OS/3 Release 5.2.) 


*0S/3 ALL 12/78 UP-8605,.6 OS/3 Technical Bulletin #6 
(This document contains 
information on the use of 
IMS 90 Multi-Thread.) 
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OS/3 TECHNICAL BULLETIN SUMMARY 


SYSTEM REL. # DATE ORDER# ITEM and DESCRIPTION @ 


*0S/3 ALL 3/78 UP-8605,.7 OS/3 Technical Bulletin #7 
(This document contains 
information concerning 
techniques for processing 
unordered IRAM files.) 


*0S/3 5.2/5.2.1 5/79 UP-8605.8 OS/3 Technical Bulletin #8 
6.0 (This document contains 
information on the use of 
CHARACTER PROTECTION MODE 
UTILITY for the UTS 400; 
this utility is available 
with Releases 5.2/5.2.1 


and 6.0.) 
*OS/3 5.2/5.2.1 5/79 UP-8605.9 OS/3 Technical Bulletin #9 
6.0 (This document contains 


information on the use of 
the IBM 3741 MEDIA 
COMPATIBILITY UTILITY 

for the UTS 400; this 
utility is available with 
Releases 5.2/5.2.1 and 6.0.) 






*OS/3 ALL 7/79 UP-8605.10 OS/3 Technical Bulletin #1 
(This document contains 
information concerning 0S/3 
FILE CATALOGING. ) 





Note: Technical Bulletins are issued as they become available, and may e 
or may not be issued in sequential order. 
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ABSTRACT 


This report is written to explain OS/3 File Cataloging. The purpose 
of this report is to provide the advanced OS/3 Job Control User 

with specific information about the file catalog and generation files. 
OS/3 Generation Files are easy to use once the cataloging mechanism 
and formulas are understood. This report will attempt to provide 

the necessary information to the Programmer to make the best use of 


OS/3 Generation Files. 
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INTRODUCTION 


The purpose of this report is to explain OS/3 Generation File cataloging and 
usage to Systems Analysts and Programmers. This report is intended for advanced 
OS/3 Job Control Users who are currently using software release levels R4.0 
through R5.2. This report also covers correction 304 and enhancements for 
Release 6.9. The report covers the following topics, as related to generation 
files: Catalog, Generation Files, Job Control Statements, Considerations for 
Cataloging, Generation Cataloging Formulas, Generation File Usage Examples, 


Correction 3204 to Rel. 5.9 (all levels) and Rel. 6.@ Fnhancements. 
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II]. FILE CATALOG 
e 
What is the OS/2 File Catalog? The OS/2 File Catalog is a svstem resident file 

" that contains information about files. $Y$CAT is the name of the File Catalog. 

. The information contained in $Y$CAT is used by the Run Processor to process 0S/3 
job control statements. The File Catalog offers data file vrotection by 
restricting unauthorized users from obtainine data fron files. It also enables 
authorized users to retrieve or create data files with a minimal number of job 


control statements. 


A catalog entry is identified by a // LBL job control statement and catalogel 
by a // CAT job control statement. Once cataloged, files are accessible ty a 
Simple reference in a subsequent job strean. For example, a portion of a strean 
to catalog a file mav look like this: 


Example 1: 


// DVC 68 // VOL DISK31 
// LEL PAYABLES 
// LFD CATFILE 


// CAT CATFILE 


In this stream, file PAYABLES is specified as bein2 on Volume DISK@1 of an 


8416 disk subsystem (logical unit number of 60). 


- July, 1979 


CN 
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To catalog this file, it is necessary to specify the same logical file name on 
the CAT statement. By matching the LFD parameter, the CAT statement links the ¢é 
aevice, volume, and file identifier to the logical file. The logical file name 
also corresponds to the DTF label in Data Management, the FD entry in COBOL, 

Tne HWAD Or WHITE statement in FORTRAN, or the file description specification 


in KPG. 


After cataloging a DVC-LFD sequence, the file definition may be used in other 


JCL streams by a reference to the file identifier only. For example: 


Y/ SOB USEIT 
// UBL PAYABLES 
// EXEC XXX 


will allow program XXX to use the file PAYABLES as cataloged in example 1. 
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IIIT. GENERATION FILES 


A. Generation File Definition 


What are generation files? Basically, a Generation File is a group of files 
with the same file identifier and a unique two digit generation number affixed 
to the end of the file identifier. The two digit generation number is affixed 
sequentially starting with zero and incremented by one until ninety-nine is 
reached, thus allowing one hundred unique labels. For example, @@ is the 
original file, @1 is the next generation, and so on. By allowing the Run 
Processorto control the generation number which is attached to the file 
identifier, a common file identifier can be used for a group of files having 
a common use. 


B. Generation File Usage 


cae Data Protection 


Data Protection is one application where generation files can be 
used. By having the Run Processor maintain a group of files for back-up 
purposes, operations personnel no longer need to perform this function. AS each 
file is created, it receives a new generation number. This procedure allows for 
the old data to be retained as back-up. The back-up data is actually any 


previous generation. Generation file usage will be explained in Section VII. 
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26 Ease of Use 


One of the benefits of using generation files and the file 
catalog is that once the file is cataloged, only one job control statement (LBL 
statement) is required to identify the data file. Through the use of cataloged, 
generation files, it is possible to eliminate a majoritv of the job control 


statements that are normally required for vrogramn execution. 
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& IV. JOB CONTROL STATEMENTS 


Job Control Statement Requirements 


This section presents specific items that should be considered when 


using the following, job control statements for generation. files: 


DVC job control statement 





1. The logical unit number on the // DVC job control statement 
should not be of the general type for disks, but must be one for 
a specific device type. This information is obtained from the 


system generation listings. 


2. The IGNORE option is not cataloged. 


VOL Job control statement 





The PREP option is not cataloged. 


DD Job control statement 





1. The // DD statement is not cataloged. 
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EXT job control statement’ 





Hs The // EXT statement is not cataloged. 


LBL job control statement 


he All parameters of the // LBL statement are cataloged. 

2. The total number of characters for the file identifier field 
is seventeen for tape files and forty-four for disk files. 
In the use of generation files, only fifteen characters for 
tape files and forty-two characters for disk are permitted. 


Two characters are used for the generation numbers. 


3. See V - Considerations for cataloging sections 5,6,7, and 8 for 


more details on use of LBL. 


LFD job control statement é 
1. INIT, RELOAD, EXTEND, and PREP parameters are not cataloged. 


B. Catalog Control Statements 


1. Entering Files in a catalog 


To catalog a file, a CAT job control statement is used. When 
the CAT job control statement is encountered, the file defined in a previous 
device assignment set is marked for cataloging at Run Processor termination. 
The file is cataloged with any qualifiers or passwords contained on the LBL 


statement. 
The format of the CAT job control statement is: 


//symbol CAT lfdname ,catpw so CR »GEN=nn 
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The CAT statement identifies the logical file name as used in 





¢ the LFD statement. Thus, the lfdname parameter of the CAT statement 


must agree with the filename parameter of a previous LFD statement. 


In some cases, the File Catalog itself may have its own password. 
Whenever the catalog is password protected, you must specify the correct 
password parameter consisting of one to six alphanumeric characters or 
access to the file catalog is denied. This procedure prevents unauthorized 
users from access to the File Catalog. The catalog password must be 
specified on all CAT and DECAT statements, if the catalog is password 


protected. 


The SCR parameter indicates that, when a subsequent DECAT job 
control statement for that file is encountered, the file should be 
scratched, not just removed from the catalog. This option is effective 
only for files specifically referenced by their full compound name in the 

6 LBL statement; if the last character of the LBL statement is a period 


or slash, the SCR parameter is not effective. 


The SCR parameter has no effect in the CAT statement in which 


it is found but does have an effect later when the file is decataloged. 


The GEN parameter indicates the maximum number of generations 


maintained on the catalog; nn may range from 01 to 99. 


In Example 2, the file defined in Example 1 is cataloged as 


a generation file. 
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Example 2: 





// DVC 68 // VOL DISK#1 
// LBL PAYABLES 
7/7 UFD CATFIL 


// CAT CATFIL,,SCR,GEN=1% 


The CAT statement in Example 2 indicates that the file defined 
by the logical file name of the LFD statement is to be put in the catalog. 
When the file is subsequently removed from the catalog, the file will 
also be scratched. A maximum of 1% generations is to be maintained in 


the catalog. 


A file that has been cataloged can now be referenced by another 


job. 


A cataloged file may not be referenced in the same stream in 
which it was entered into the catalog. The file is cataloged at the end 


of the job stream, when /& is encountered by the Run Processor. 
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2. Removing Files From a Cataloe 


& To remove a file from the catalog, a DECAT job control statement must be 
used. The file to be removed is defined by the LBL statement and designated by 
the logical file name on the DECAT statement. The LFDname varameter of the 
DECAT statement must agree with the file name parameter of the LFD statement in 


a previous device assignment set. 
The format of the DECAT job control statement is: 
//synbdol DECAT 1lfdname [,catpw] [,SCR] [,GEN] 


The catpw parameter is a il to 6 Character alphanumeric password to allow 


changes to the File Catalog. 


@ Once the catalog is password protected, subsenouent CAT or DECAT statements 
cannot be used without using this password. The SCR parameter, if previously 
specified on the CAT statement, will scratch the file as well as remove it fror 
the catalog. The GEN parameter removes all senerations specified for the file 


from the catales. 
Example 3 removes a file identifier from the cataloe. 


pxarple 3: 
// LBL PAYABLES 
ff GED CATEILE 


© // DECAT CATFILE,, SCR 
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V. CONSIDERATIONS FOR CATALOGING 





This section addresses those areas that may cause misunderstandings and 
problems for the user. By highlighting, and in some cases, repeating the 
requirements for Generation File usage, it may prevent the occurrence of major 
problems during implementation. Presenting these items before the examvles are 


Shown, (Section VII), should make the examples easier to follow. 


1. The catalog entries representing files and the files themselves are not one 
and the same. Remember, that operations on the File Catalog do not effect the 
actual data file. Specific functions can be performed, such as the SCR 
function, which clears both the File Catalog and the VTOC of the file 
identifier. It must be emphasized that the cataloe entries repre- 
senting files aid the files are separate entities. 

@ 
2. // CAT and // DECAT work together in scratchine files. If the SCR parameter 
is specified on the CAT statement, a single file (or one generation of a file) 
is scratched and removed from the catalog automatically whenever a subsequent DECAT 
job control statement is encountered for the named file. If the SCR parameter 
is only entered on the DECAT statement, the file is removed from the catalog 
and scratched. If the GEN parameter is specified on the DECAT statement, all 


generations of a file are removed from the catalog, but no files are scratched. 


3S. Each cataloged file must have a unique file identifier (LBL). An 
uncataloged file can only be cataloged, by the CAT job control 
statement. When cataloged, the entire device assignment set for the file must 


be given, but the file space is not allocated (i.e., no EXT statement is 


required). & 


OS/3 Technical Bulletin #10 -12- July, 1979 











4. Any previously cataloged file may be referenced by a single LBL statement 
containing only the file identifier. No other device assignment statements are 
required since the information is now contained in the catalog. DVC and VOL 
statements are not required. Referring to Example 1 to reference the file 


PAYAELES, all that is needed is: 


// LBL PAYABLES 
5. When a // LBL job control statement is processed, the catalog is searched 


for that file identifier (whether the file is being accessed through the 


catalog or not) so password verification can be done. 


6. To provide the necessary catalog information about a file, the LBL job 
control statement is expanded to include file information for a catalos. The 


basic format of the LEL statenent is: 


// LBL file-ia 
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To append file infcrmation for a catalog, the file-id field is further 


defined to be: € 





file qualifier quel 
file identifier level-id 
file-id= generation number +n 
~n 
nn 
passwords (rpw/wpw ) 


Thus, the format shewing the file-id parameters for a catalce definiticn 


becomes: 


+n 
// LEL {qual/] level-id1 [.level-id2] ... [.level-idn]] <-n ((rpw/epe) 
Le n _ 
7. Fellowing the file-id parameter cn the // LBL statement is the eeneraticr 
number parameter. The generation number can te specified in one of three ways: 
+n, ~n, or mn. Jhe symbol nn represents an absolute generation. The +n prevides 
the increment value for the creation of a new eeneraticn of a file. The plus 
Sign (+) must be coded. The -r is used as a relative reference number, 
(relative to current), when accessing an clder or previous generaticn number. 
The minus sign (-) must be coded. If 9S generations are exceeded, the 
generation number goes back to zero (€@). For generation files, a catalog 


update is performed when a pcesitive (+) relative eeneraticn is given. 
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8. The labels are stored in the catalog using a hierarchical 
method to facilitate faster scans of the catalog. With a label 
name, the levels of the hierarchy are separted by a '/* (for 


qualifiers) or by a'.'. 


The catalog is scanned by first looking for a match on the first 
level. When this is found, the first level entry points to all 
entries at the next level; etc. 


For example, assume the following file labels were cataloged: 


ABC . XYZ . 123X 
ABC . XYZ . 456X% 
ABC . TUV 

DEF / XYZ 

DEF / TUV 

XFILE 


The internal structure of the catalog would be: 


Record lL 


Record 2 


Record 3 


Record 4 





If the program requests label DEF/TUV the first level Of the 
heirarchy is searched for 'DEF/', when this is found it points 


to the second level which is at record 4 in this example. 
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The next level is searched for 'TUV', when found, it contains the 


cataloged file information. 


Most catalog users have a large number of entries in the first level. 
The first level typically spans a number of records and is time consum- 
ing to scan. The // QUAL qualname job control statement specifies the 
first level of the heirarchy whith is automatically prefixed to all 
file labels in the job stream. The run processor also notes the 
position in the catalog of the qualname, thus speeding up the first 


level search of the catalog. 
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g. When a generation file on disk is beine created, an EXT statement must be 

included in the file assignment set to allocate disk svace for the new file. If 
e a new generation is to reside on a volume different from the current 

generation, Tv and LFD statements must also be included. A new generation 


member is only created via a positive relative reference. 


1Q. If a DVC or VOL job control statement is included in a device assignment 
set which references a cataloged file, then the entire device assignment set, 
(the DVC through LFD sequence), must be specified. If a permanent change is to 
be made to the device assienment set for a cataloged file, the file must be 


recataloged. 


ll. A generation file has to be explicitly cataloged only once (bv the CAT job 
control statement). For example, the following two jobs, when run in the order 
Shown, result in the cataloging of the multigeneration file that has a file 


& identifier of GEN: 
Example 4: 


// JOB CAT 

// DVC 63 // VOL DSP@O1 
// LBL GEN // LED A 

// CAT A,,,GEN=3 

/& 

// FIN 

// JOB CATL 

// UBL GEN+1 

/& 


© // FIN 
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Notice that a CAT job control statement is not needed in the second job. 





12 . The actual catalog update for CAT and DFCAT job control statements or 
automatic generation operations (+n) is performed when the /& job control 
statement for that job is processed by the Run Processor If the control stream 
contains errors severe enough to inhibit the queuing of the job, the cataloe 
operation is not verformed. The reasons for upiatine the File Catalog at this 
point are to avoid locking out other jobs which reference the catalog, and to 
ensure that generation references within a job are consistent. In general, this 
means that while a file nay be referenced (by its file name) in the job which 
catalogs it, the infermation to be cataloged is not available to job control in 
the same job. For instance, assume that the file identified as GEN is 


cataloged. The following control stream would result in an invalid reference: 


Example §: @ 


// JOB GEN2 
// DVC 63 // YOL DSP828 


// UBL GEN+1 // LFD B 
2 // LBL GEN+1 // LFD C 
/6 
// FIN 
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The file name of B in the LFD job control statement (1) would explicitly 
® generate a file control block for volume DSP@28. The file name of C in the LFD 
jobd control statement (2) would obtain the most recently cataloged information 
in volume DSP@21. If two LBL job control Statements with new DVC andi VOL 
information are in the same job (as in Example 5), the second LBL reference 
obtains the DVC and VOL information from the previous generation. If these two 
references had been in separate jobs, no conflict would have occurred; or, the 
DVC and VOL job control statements for volume DSP@28 could have been reveated 


in the second reference (2). 


In a job where more than one update to the catalog occurs, three courses of 


action are possible for catalog manipulation. You can: 
1. Run the catalog updates as separate jobs; 


2. Use only one device assignment set for the file to be cataloged, 
one LBL statement, and make all references to the file name on one LFD job 


control statement; or 


ie Duplicate the device assignment set (with different file names) 


for each reference. 
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VI. GENERATION CATALOGING FORMULAS 





The following formulas are used by the run symbiont in determining which 
generation file information should be used for creatine the next catalog entry, 
when no DVC and VOL information is specified in the job stream. The formulas 
are only used when the generation number on the // LBL statement is plus (+n). 
The formulas are: 

1. If T+1>N take the first (oldest) entry. 


2. If T+1<N take the last (newest) entry. 


T is equal to the nunber of generation members in the catalog for a svecific 


file-id. & 


N is equal to the number of generations specified on the GEN parameter of the 





// CAT statement. 


Formula number one is read as follows: 


If T (number of generation members in the catalog) plus one is greater than N 
(the number specified by the GEN parameter), then take the information from the 
oldest active entry in the catalog for that file-id and vlace it in the entrv 


to be created. 
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Formula number two is read as follows: 


If T (number cf generation members in the catalog) plus one is less than or 
equal to N (the number specified ty the GEN parameter), then take the 
information from the latest active entry in the cataloe for that file-id and 


place it in the entrv to be created. 
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VII. EXAMPLES OF GENERATION FILE USAGE 





The purpose of this section is to provide the user with actual job con- 
trol streams and visual representatives of the way the generation catalog 
mechanism actually works. The section is divided into three parts: 
Creating Generation Files, Maintaining Generation Files, and Generation 


File Problems and Solutions. 


A. Creating Generation Files 


This part presents examples that show how to enter a generation 
file into the File Catalog. Included in the examples are step-by-step 
procedures showing the effect that specific 05/3 job control statements 
have on the catalog, and the data files represented by those catalog @ 
entries. All of the illustrations attempt to parallel generation catalog 


structure and file usage between single volume users and separate volume users 





Comparing the two different catalog structures side by side shows the 


benefits of each type. 


Example 6 Step 1 shows the job control required to catalog a 
file called INV. The maximum number of generations maintained are 
three (GEN=3). Notice that the job control and catalog entries for 
Single volume and separate volume users are the same. The example also 
shows that an entry can be made in the catalog without creating a 


file. However, working with the catalog and the file separately 


should be avoided. 
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// 
// 
// 
ne 
// 
// 
/& 





The job control statement // CAT produces a 


Step 1 consists of putting an entry of 


catalog. 


Example 6: 


Single volume 
JOB CATALOG 
DVC 62 
VOL DISKZ1 
LBL INV 
LFD NEWINV 


CAT NEWINV,,,GEN=3 


the structures shown in Figure 1: 
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Ps Re 


INV as a base file identifier into 


separate volume 


// 
i 
// 
// 
// 
// 
/& 


JOB CATALOG 


DVC 6 
VOL DISK@1 
LBL INV 
LFD NEWINV 


CAT NEWINV,,, GEN=3 


three generation cataloe file with 
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VOLUME 


STRUCTURE 
(FILES) 
DISko! 
EMPTY 
VOLUME 
STRUCTURE 
CATALOG (FILES) CATALOG 
STRUCTURE STRUCTURE 
(ENTRIES) (ENTRIES) DISKOZ 





DISKOZB 


| | 


ONE VOLUME THREE VOLUMES 


*means current generation 


FIGURE 1. MULTIGENERATION CATALOG FILE BUILDING STEP 1 
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A catalog file entry has been generated that links the file identifier to 


the disk volume, even thoueh no extent has been allocated and no file created. 


The second step (Example 7) creates the file. Tape and cards are used to 


puild a file. The file identifier as defined and cataloged in the first step 


is generation undated in the second step. 


It is only necessary to specify 


the // LBL, // EXT and the // LFD to create the new output file. 


Example 7: 


// 
// 
// 
// 
// 
// 
// 
// 
/$ 


{> 
/& 


single volume 


JOB CREATE 
DVC 90 

VOL INSAV 
LFD INPUT 
LBL INV 

EXT ,,,CYL,1 
LFD OUTPUT 


EXEC BUILD 


new records 


// JOB 
// DVC 
// VOL 
// “FD 
// UBL 
// EXT 
// FD 


Separate volume 


CREATE 
98 

INSAV 
INPUT 
INV 

»9 ,CYL,1 
OUTPUT 


// BXEC BUILD 


/$ 


new records 


(* 
/& 


Figure 2 shows the state of the catalog and the disk files after an update 


has been performed. 
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VOLUME 
STRUCTURE 
CFILES) 


VOLUME 
CATALOG E S 
STRUCTURE ie CATALOG 
(ENTRIES) STRUCTUDRE 
CENTRIES) 


oo 


rs 





ONE VOLUME THREE VOLUMES 





FIGURE 2. MULTIGENERATION CATALOG FIIE BUILDING STEP 2 
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The third step (fxample 8) is to update file INV to a second generation ani 
& allocate the file on volume DISK#1 for single volume usage or DISK#@2 for use 


with three volumes. 


Example 8: 


single volume Separate volume 
// JOB UPDATE // JOB UPDATE 
// LBL INV // LBL INV 
// LED INPUT // LED INPUT 
// LBL INV+1 // DVC 68 
fi EX? 3 0VU // VOL DISK82 
// LED OUTPUT // LEL INV+1 
& // EXEC MERGE // BXT ,,,CYL,1 
/$ // LED OUTPUT 
new records // EXEC MERGE 
/* /$ 
/& new records 
/* 
/& 


Fieure 3 illustrates the basic difference between one volume andi three 
volume processing. Note, that the second generation (INV@1) of this file is on 
a separate disk (DISKg@2) The use of several disks for processing helrs protect 


data. 
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VOLUME 
STRIJICTOURE 


(FILES) 


VOLUME 
caraoe == STRUCTURE nine 
STRUCTURE (FILES) STRUCTURE 
(ENTRIES) (ENTRIES) Corson) 
C¥) 





Ci 


ONE VOLUME THREE VOLUMES 


FIGURE 3. MULTIGENERATION CATALOG FILE BUILDING. STEP 3 
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The fourth stev (Example 9) in this process completes the generation 


sequence for building the catalog. Figure 4 shows that both one and three 


r volume users have three generations in the catalog. 


Example 9: 
Single volume 


// JOB UPDATE 

// UBL INV 

// LED INPUT 

// UBL INV+1 

// BXT 5,5CYL,2 

// ED OUTPUT 

// EXEC MERGE 
@® +; 

new records 
/* 
/& 
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// JOB 
// UBL 
// “FD 
// DVC 
// VOL 
// UBL 
// EX? 
// FD 


Separate volume 


UPDATE 
INV 
INPUT 
68 
DISK®S 
INV+1 


ry ,CYL,1 


OUTPUT 


// EXEC MERGE 


/$ 


new records 


/* 
/& 
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Figure & shows the catalog and file structure that would result if uvdating 


of the catalog and allocating of files would continue. 
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FIGURE 5. MULTIGENERATION CATALOG FILE BUILDING STEP 5 
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A point to keep in mind about generation numbers is that after veneration 
@ runver 99, the numbers begin again with @d8. The catalog structure would look 


like: 


SY$CAT 
(=2) ae 
iy ages 
ie ee 


B. Maintaining Catalog Files 


& This section shows how to maintain the catalog and the data files. Through the 
use of job control, it is possible to build job control streams that maintain 
the catalog and files at their best operating efficiency. Examples 129 through 


14 in this section present only one method of catalog and file maintenance. 


Example 12 uses the same basic first step that Example 5 used for 


cataloging the file. However, the next stevs are different. The job control 





stream is constructed to scratch the oldest generation file after each update 


to the new file. 
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Example 10: 





// JOB CATALOG 

// DVC 6H = =// VOL DISK#1 
// UBL INV 

// LED CATFILE 

// CAT CATFILE,,,GEN=3 
/& 


Example 11 shows how to set upa volume by allocating three files in one job 
step, without actually placing any data in the files. The structures are 


shown in Figure 6. 


Example 11: 





// JOB ALLOC 

// LBL INV+1 

ff BP ge CT yl 
// LFD FILEL 

// LEL INV+2 
SPE oy Gel gt 
// LFD FILE2 

// LBL INV+3 

LE ERD weg lt bt 
// LFD FILES 

/6& 
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CATALOG 


= = VOLUME 
STRUCTURE See 
(ENTRIES) i 
DISKO! 
e = 
EMPTY 
@ FIGURE 6. MULTIGENERATION UPDATE CATALOG FILE BUILDING. STEP 1 


aie (Refer to Example 10) 
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The run processorhas been instructed to maintain three generations. 


The file identifiers are automatically placed in the catalog as shown 


in Figure 7. 





them. 
VOLUME 
CATALOG STRUCTURE 
STRUCTURE (FI a ES) 
LENTRIES) Core") 
omer Cempru) 
Newey oer 
wy a 
FIGURE 7. MULTIGENERATION UPDATE CATALOG FILE BUILDING. STEP 2 
(Refer to Example 11) 
OS/3 Technical Bulletin #10 -34- 


The files are also allocated but have no data written to 








July, 





The file can now be built or filled by constructing the control stream 


e& shown in Example 12:. 
Example 12: 


// JOB CREATE 
// DVC 92 

// VOL INSAV 

// UFD INPUT 

// LBL INV 

// LFD OUTPUT 
// EXEC EBUILD 


/$ 
new records 
rae 
& This of course, assumes that a build program has been previously 


constructed to build the file. The job stream would then place it on the Diskd1 


volume. The volume would now look like Figure 8. 
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FIGURE 8. MULTIGENERATION UPDATE CATALOG FILE BUILDING. 
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(FILES) 


(-2) oe (EMPTY) 
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(Refer to Example 12) 
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STEP 
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we 

















INV@3 would be the current file (*) and receive the data. To add an updatea 
Osc the oldest file would be scratched at the same time and thus retain 


only the three active files listed in the catalog. This would have the 


advantage of keeping the number of files on the volume to a minimum. 


In addition to scratching the oldest file, a SKIP job control statement 
could be placed in the control stream. If a fatal error occurred while 
updating, the newly created generation would automatically be decataloged. 
This would keep the catalog generation number current with the active files 


on the volume. Example 13 would accomplish this action for the user. 


If the new file is built by merging the current file with the new records, 


the catalog and file structures look like this: 








VOLUME 
eae STRUCTURE 
TALOG 
Papen y= (FILES) 
a 
eee, (AVALLABLE ) 
Newz bai 
(FULL) 
(FULL) 
& FIGURE 9. MULTIGENERATION UPDATE CATALOG FILE FUILDING. STEP 4 
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Take notice of the fourth file allocated to the volume in this sten. 
@ 

The SKIP job control statement (Example 13) checks the UPSI byte to 
determine if that file has been accepted. The file identifier with generation 
four has been added to the catalog and generation four now becomes the current . 
generation. If the file is accepted, the bdranch to FRR is not taken and 
processing goes On to scratch the oldest file. This is accomplished by 
referencing INV-2 in the // LBL statement with an // LFD of OLDEST. Another 
SKIP statement will eet us over the error RUN job stream call to a NOP job 
control statement, which is merely a convenient nonoveration used as a target 
pranch. If an error had been encountered during the merge operation, the SKIP 
statement would have bypassed to the job control statement that tells us to run 


the job BACKUP. 
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Example 13: 

& 
// JOB UPDATE 
// LBL INV 
// LED INPUT 
// LBL INV+1 
// EXT ,,,CYL,1 
// LED OUTPUT 
// EXEC MERGE 
/$ 

new records 

/* 
// SKIP ERR,1 
// LBL INV-2 

& // LED OLDEST 
// SCR OLDEST 
// SKIP OUT 
//ERR RUN BACKUP 
//OUT NOP 
/& 
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At this point we would want to decataloe the file identifier for generation 
four and also scratch the file built. This job stream would look like: 





Example 14: 


// JOB BACKUP 

// LBL INV 

// LFYD NEWBAD 

// DECAT NEWBAD, ,SCR, ROL 
/& 


Refer to Section VIII. Changes for Current Release for a description of the 


ROL parameter. 


This would return the catalog to its previous state where INV@1, INV@2, and 
INV@3 would be the only files. @ 


If the job stream in example 13 ran successfully, the following 
structures (Figure 1%) would be produced if a fourth entry for the catalog were 


made, but only three maintained. 


OS/3 Technical Bulletin #10 —-40— July, 1979 











VOLUME - 
CATALOG STRUCTURE 
STRUCTURE (FILES) 
(ENTerES) C15K0") 
err ia 
ers as WHBLE) 
-l 
¢C (FOL) 





e : oH ey ULL) 


@& FIGURE 19. MULTIGENERATION UPDATE CATALOG FILE BUILDING. STEP 5 


(Example 13 successful) 
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INV@5 would become the current generation, but since there are only four 
files specified, INV@5 goes into the only available catalog space (previously © 
specified as INV@1). INVS2 is deleted from the catalog, since the catalog only 
maintains three, and now the INV@2 catalog space becomes available. INV@%2 is 
also scratched from volume DISK@1. 


C. Generation File Problems and Solutions 


This last section shows how to manipulate the catalog and files to circumvent 
normal problems of day to day overations. The examples show the outcome when no 
action is taken and when a recovery method is used. The solutions presented are 
not the only solutions available but can be used as a basis for other 
solutions. One volume generation files and three volume generation files are 


used to parallel the example in Section VII A. Generation File Usage. The 


following problems will be used: 
1. in a one volume application, a file, INV@2, is accidently 


scratched and 


Ze ina three volume application, pisxg2, is accidentally 


destroyed. 


The first step of this procedure is to DECAT the catalog entries (as shown 
in Example 15). This creates a gap in the generation sequence (Figure 11). The 
first alternative is to continue processing and ignore what has happened. This 
is totally acceptable. However, it should be noted what happens to the volume 


rotation when a gap is left in the catalog for a generation sequence. 





4 = 
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@ Example 15: 


Single volume multivolume 
_ (file INV@2 accidently scratched) (disk pack DISK @2 accidently destroved) 
// JOB DECAT // JOB DECAT 
// LBL INV=1 // LBL INV=1 
// LED COR // LED COR 
// DECAT COR // DECAT COR 
/& /& 
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ONE VOLUME THREE VOLUMES 


FIGURE 11. MULTIGENERATION CATALOG FILE USAGE. STEP 1 
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To get around the problem of a missing file or disk pack from the generation 


| sequence, requires no special control statements (see Frample 16). 


Example 16: 


Single volume multivolume 
// JOB UPDATE // JOB UPDATE 
// UBL INV // LBL INV 
// LFD INPUT // LFD INPUT 
// LBL INV+1 // LBL INV+1 
Ff ERT 6g €T G1 ff EXT asaCltel 
// LFD OUTPUT // LFD OUTPUT 
// BXEC MERGE // EXEC MERGE 
/$ /$ 

@ new records new records 
f= Vhs 

/& /& 


The gap created by a missing file has no real effect in the one volume 
environment except that the file cannot be accessed without its cataloe entry. 
The file is no longer available for processing (scratched accidently). This 
causes no problem. The same holds true for the missing disk pack. However, note 


where INV@4 is placed. See Figure 12. 
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FIGURE 12. MULTIGENERATION CATALOG FILE USAGE. STFP 2 
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Example 17 and Figure 13 show what can be done toc re-create an entry into the 


catalog so that all vreviously programmed catalog functions remain operational. 


Notice in the three volume processing, that replacing the gap with another 


usable file-id and disk volume, 


that the volume rotation abilities are retaineil 


and that INV@4 is automatically placed on Disk@1. Also, note the difference in 


the job control streams for this example from the previous one. 


Example 17: 


single volume multivolume 
// JOB RECAT 
// DVC 62 
// VOL DISK2A 
// LBL INV-1 
// LFD REDO 
// CAT REDO,,,MEM 
/ & 
// JOB UPDATE // JOE UPDATE 
// UBL INV // UBL INV 
// LED INPUT // LFD INPUT 
// LBL INV+1 // LBL INV+1 
// EXT. seeCYL,1 fe). ae os | Ree 
// LED OUTPUT // LED OUTPUT 
// EXEC MERGE // EXEC MERGE 
/$ /$ 
new records new records 
/* 7* 
/& /& 


Note the location of 


INVO4 in the three volume illustration. 
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When a File Catalog problem is encountered, follow accepted procedures for the 


Software User Report (SUR). Helpful information that should be supplied with 


& the SUR is: 


ts JCSCAT display of file catalog 
2. disk print of $YSCAT, using the System Utility and 
3. job stream where the problem was encountered. 


2Ag= 
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VIII. CHANGES FOR CURRENT RELEASE 


The following are changes in Rel. 6.8 and correction number 204 for Rel. 5.@. @ 


A. DECAT Statement 


A new parameter value has been established for the fourth positional 
parameter of the DECAT statement. This is the ROLLBACK parameter. Only the 


first three characters (ROL) of the parameter are required. 


The format of the DECAT statement is: 


// symbol DECAT lfdname [,catrpw] [,SCR] ce 


lRor 


Rollback is used when there is a need to reset a generation file’s status to a 





previous condition, i.e., back to the status which existed prior to the last 


update of the file catalog for the file in question. 


Rollback will remove the current member of a generation file, making the 
previous member current, and insert the current member as the oldest member of 


the generation, with appropriate adjustment to label. 


Rollback can only be used against the current member of a generation file, and 
can only apply once to the current member within a single job. Thus, within a 
Single job a particular generation file can be reset by one member. More than 


one unique generation file can, however, be rolled back within a single job. 
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NOTE: 


The new status of the generation file being rolled back can only be accessed in 


& a subsequent job. 


. AS an example of rollback, assume that a eeneration file (// LBL FILE) has been 





established and used with four generations (GEN=4) and maintained in the file 


catalog. The current status of the generation file is: 


FILE25 current-3 VSN=A 
FILE26 current-2 VSN=B 
FILE27 current-1 VSN=C 
FILE28 current VSN=D 


It has been determined that the last update of the file catalog must be 


S reprocessed. 


The following statements can then be used: 
// UBL FILE 
// UFD RESET 


// DECAT RESET,,,ROL 


The new status of the generation file is: 


FILE24 current-3 VSN=D 
FILE25 current-2 VSN=A 
FILE26 current-1 VSN=B 
& FILE27 current VSN=C 
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The statements in this example restore the generation file to the condition 


that existed before the last member (VSN=D) was added to the file. € 


During rollback, if the current member to be removed is also to be scratched 


from its volume, the following sequence could have been used: 


// LBL FILE 
// LFD RESET 
// DECAT RESET, ,SCR,ROL 


If a new volume-serial-number, X, is desired for the oldest member established 


during rollback, the following sequence could be used: 


// DVC 67 
// VOL X 





// LBL FILE 
// LFD RESET 
// DECAT RESET,,,ROL 


The new status of the generation file is: 


FILE24 current-3 VSN=X 
FILE25 current-2 VSN=A 
FILE26 current -1 VSN=B 
FILE27 current VSN=C 
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If a generation file does not have a full complement of members, the current 
@ wcarer will be removed, but a new oldest member will not be inserted. A warnine 
message of partial rollback (R521) will be provided by the Run Processor for 
“this condition (see Job Control Error Messages). 
The absence of a full complement can be indicated by the followirg for a file 


created with GEN=4: 


FILES? current-2 VSN=A 
FILEO1 current-1 VSN=B 
FILEQ2 current VSN=C 


A rollback against this file will produce: 


@ FILES current-1 VSN=A 
FILEO1 current VSN=B 


EF. CAT Statement 

A new parameter value has been established for the fourth positional parameter 
of the CAT statement. This is the MEMBER parameter. Only the first three 
characters (MEM) of the parameter are required. 


The general format of the CAT statement is: 


//syndol CAT lfdname[,catpw][,ScR] [, GEN=nn ] 
{ MEM j 
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Member is used when a gap has to be filled among members of a generation file. 


This gap must have been established in a job prior to the one containing the 





MEM parameter. A DECAT statement and a CAT statement with the MEM parameter ¢ 


cannot be used against the same member of a generation file in the same job. 


A full device assignment set (DVC-LFD sequence) must be used to reestablish a * 


member. 
For example, a generation file (// LBL FILE) has been established ani used witt 
three generations (GEN=3). A non-current member has been decataloged. The 


current status of the generation file is: 


FILES2 current~-2 VSN=A 


(gap) 
FILES4 current VSN=C 





It is desired to fill the gap. 


The following statements can be used: 
// DVC 92 
// VOL B 
// LBL FILE-1i 
// UFD FILL 
// CAT FILL,,,MEM 
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The new status of the generation file is: 


FILES2 current~-2 VSN=A 
FILES3 current-1 VSN=B 
FILES4 current VSN=C 


The most likely use of the MEM parameter is to replace the oldest member of a 
generation, in order to insert a new volume-serial-number to be picked up at 


the next incrementation of that generation. 


Thus, if the status of the generation file is 


FILE?75 current-2 VSN=A 
FILE76 current-1 VSN=B 
& FILE?? current VSN=C 


The oldest member of the decataloged using 
// LBL FILE-2 
// LFD REMOVE 


// DECAT REMOVE 


leaving the generation file status as 


(gap) 
FILE?76 current~-1 VSN=B 
FILE?7 current VSN=C 


-55- 
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In a separate job, a new member can be inserted using 





// DVC 90 

// VOL X 

// LBL FILE-2 

// LFD REP 

// CAT REP,,»MEM 


The new status of the generation file is then 


FILE75 current-2 VSN=X 
FILE76 current~-1 VSN=B 
FILE?7 current VSN=C 





The next update, using 
// UBL FILE+1 
will pick up volume~serial-number X. 
C. LFD Statement 
It is frequently required that a tape volume be prepped prior to its use as an 
output file. When the tape volume in question contains a generation file, it is 


advantageous to prep the volume without having to give the explicit 


volume~serial-number designation. 
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A new parameter value has been established for the third positional parameter 
of the LFD statement in order to accomplish this. The parameter is PREP, and 
indicates that the tape volume(s) for the file in question are to be vrevped 


prior to use. 


The format of the LFD statement is: 
//{symbdol] LFD |filename n +f ACCEPT 
e 


*Pilenam S EX TEND 
INIT 
RELOD 


» PREP 


For example, given the generation file (// LBL FILE, GEN=3) status: 


FILE1i5 current-2 VSN=A 
€ FILE16 current-1 VSN=B 
FILE? current VSN=C 


the statements 


// LEL FILE+1 
// LED OUTPUT,,PREP 


will have the same effect as 


// DWC 98 

// VOL A(PREP) 

// LBL FILE+1 
& // LED OUTPUT 
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The new status of the generation file is: 











FILE16 current-2 VSN=B 

FILE17 current-1 VSN=C , 

FILE18 current VSN=A “ 
-58- 
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IX. JOB CONTROL ERROR MESSAGES 
R531 


A write password has been specified on a LBL statement, but there is no write 


password for this file in the file catalog. 


R539 


A read password has been specified on a LBL statement, but there is no read 


password for this file in the file catalog. 
R528 


Rollback is being requested in a DECAT statement against a file which is either 


not a generation file or not the current member of a generation file. 


R527 


A request has been made to decatalog an entire generation file, but the file 


identified in the DECAT statement is not a generation file. 
R526 


A member of a generation file, which is to be inserted through the use of the 


MEM parameter of the CAT statement, is already present in the file catalog. 
R525 


@: CAT or DECAT statement is being used more than once against the same file. 


OS/3 Technical Bulletin #10 Hegu July, 1979 





R524 


The label for the file to be cataloged as a generation file is too long. The 
maximum for tape files is 15 characters; the maximum for disk files is 42 
characters. 

R522 

The file to be cataloged does not reside on tape or disk. 


R521 


True rollback cannot be achieved for the file identified in a DECAT statement. 


Only partial rollback will be performed. 


R528 


The file identified for decataloging is not in the file catalog. This message 


will only appear when a full DVC-LFD sequence is used to identify the file. 


R518 


A MEMEER parameter has been encountered on a DECAT statement, or if on a CAT 


statement, the sign used with the LBL statement is not negative. 


R517 


A ROLLBACK parameter has been encountered on a CAT statemert. It can only 


appear on the DECAT statement. 
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R463 


A non-current member of a generation file has not been found in the file 


catalog. This indicates the presence of a gap between consecutive generation 


members. 


-61- 
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